%
% `SGTime.tex' -- describes the SGTime class
%
%  Written by Curtis Olson.  Started July, 2000.
%
% $Id: SGTime.tex,v 1.1.1.1 2002/09/07 02:58:20 curt Exp $
%------------------------------------------------------------------------


\documentclass[12pt]{article}

\usepackage{anysize}
\papersize{11in}{8.5in}
\marginsize{1in}{1in}{1in}{1in}

\usepackage{amsmath}

\usepackage{epsfig}

\usepackage{setspace}
\onehalfspacing

\usepackage{url}


\begin{document}


\title{
    SimGear \texttt{SGTime} class.
}


\author{
    Curtis L. Olson (\texttt{curt@flightgear.org}) \\
    Durk Talsma (\texttt{d.talsma@direct.a2000.nl})
}


\maketitle


\section{Introduction}

The \texttt{SGTime} class provides many real-world time values.  It
calculates current time in seconds, GMT time, local time zone, local
offset in seconds from GMT, Julian date, and sidereal time.  All of
these operate with seconds as their granularity so this class is not
intended for timing sub-second events.  These values are intended as
input to things like real world lighting calculations and real
astronomical object placement.


\section{Synopsis}

\begin{verbatim}
#include <simgear/timing/sg_time.hxx>

SGTime time_params( const string& root );
SGTime time_params( double lon, double lat, const string& root );
\end{verbatim}


\section{\texttt{SGTime}}

To properly use the \texttt{SGTime} class there are a couple of things
to be aware of.  After creating an instance of the class, you will
need to periodically (i.e. before every frame) call the
\texttt{update()} method.  Optionally, if you care about updating time
zone information based on your latitude and longitude, you can call
the \texttt{updateLocal()} method periodically as your position
changes by significant amounts.

\subsection{Constructor}

\begin{verbatim}
SGTime time_params( const string& root );
SGTime( double lon, double lat, const string& root );
\end{verbatim}

This creates an instance of the \texttt{SGTime} object.  When calling
the constructor you need to provide a root path pointing to your time
zone definition tree.  Optionally, you can call a form of the
constructor that accepts your current longitude and latitude in
radians.

If you don't know your position when you call the \texttt{SGTime}
constructor, you can just use the first form (which assumes 0, 0).

\subsection{Periodic Updates}

\begin{verbatim}
// Update the time related variables
void update( double lon, double lat, long int warp );
\end{verbatim}

The \texttt{update()} method requires you to pass in your position and
an optional time offset in seconds.  The offset (or warp) allows you
to offset ``sim'' time relative to ``real'' time.  The
\texttt{update()} method is designed to be called by the host
application before every frame.

\begin{verbatim}
// Given lon/lat, update timezone information and local_offset
void updateLocal( double lon, double lat, const string& root );
\end{verbatim}

The \texttt{updateLocal()} method is intended to be called less
frequently -- only when your position is likely to be changed enough
that your timezone may have changed as well.  In the FlightGear
project we call \texttt{updateLocal()} every few minutes from our
periodic event manager.

\section{Accessor Methods}

Once an instance of \texttt{SGTime} has been successfully initialized,
you may access valid data from it.

\begin{verbatim}
time_t get_cur_time();
\end{verbatim}

Returns the current Unix time in seconds.

\begin{verbatim}
char* get_zonename()
\end{verbatim}

Returns the time zone name (for your current position.)

\begin{verbatim}
struct tm* getGmt()
\end{verbatim}

Returns the current ``broken down'' GMT time.

\begin{verbatim}
inline double getJD() const { return jd; };
\end{verbatim}

Returns the current Julian date.

\begin{verbatim}
inline double getMjd() const { return mjd; };
\end{verbatim}

Returns the current modified Julian date.

\begin{verbatim}
inline double getLst() const { return lst; };
\end{verbatim}

Returns ``local'' sidereal time for your position.

\begin{verbatim}
inline double getGst() const { return gst; };
\end{verbatim}

Returns sidereal time at longitude = 0.


\section{Utility Functions}

In addition to the \texttt{SGTime} class, \texttt{sg\_time.hxx} also
provides several utility functions which don't make sense to live
inside the class.

\begin{verbatim}
time_t sgTimeGetGMT(int year, int month, int day, 
                    int hour, int minute, int second);
\end{verbatim}

Returns unix time in seconds for the given data (relative to GMT)

\begin{verbatim}
inline time_t sgTimeGetGMT(struct tm* the_time);
\end{verbatim}

A convenience wrapper for the above function that takes the arguments
in a different form.

\begin{verbatim}
double sgTimeCalcMJD(int mn, double dy, int yr);
\end{verbatim}

Returns modified the Julian date give a month, day, and year.  This is
the number of days elapsed since 1900 jan 0.5 and is adapted from Xephem.

\begin{verbatim}
double sgTimeCalcGST( double mjd );
\end{verbatim}

Return the greenwich mean sidereal time, given an mjd.

\begin{verbatim}
char* sgTimeFormatTime( const struct tm* p, char* buf );
\end{verbatim}

Format the time for output.

\end{document}
